\documentclass[letterpaper]{article}

%
% Package setup
%

\usepackage[utf8]{inputenc}
\usepackage[scale=0.75]{geometry}
\usepackage{chngpage}
\usepackage{calc}
\usepackage[bottom]{footmisc}

\usepackage{fancybox}
\usepackage{fancyhdr}
\usepackage{lastpage}
%\usepackage{titling}

\usepackage{color}
\usepackage[colorlinks]{hyperref}
\usepackage{graphicx}
\usepackage{float}
\usepackage{listings}


%
% Document Setup
%

\newcommand{\mytitle}{Ruby Software Construction}
\newcommand{\mysubtitle}{User Guide}
\newcommand{\myauthors}%
	{Chandler Carruth, Matthew Holt, Adam Humenansky, Billy Scott}
\newcommand{\myauthorsbrief}{Carruth, Holt, Humenansky, Scott}
\newcommand{\myclassnum}{CSC 631}
\newcommand{\myclassname}{\myclassnum: Software Engineering}
\newcommand{\mysemester}{Spring 2007}

\setlength{\parindent}{0pt}
\addtolength{\parskip}{0.5\baselineskip}

%\raggedright

\newcommand{\Make}{\texttt{Make}}
\newcommand{\Makefile}{\texttt{Makefile}}
\newcommand{\Makefiles}{\texttt{Makefile}s}
\newcommand{\Automake}{\texttt{Automake}}
\newcommand{\Autoconf}{\texttt{Autoconf}}
\newcommand{\Autotools}{\texttt{Autotools}}
\newcommand{\CMake}{\texttt{CMake}}
\newcommand{\JAM}{\texttt{JAM}}
\newcommand{\BoostJAM}{\texttt{Boost::JAM}}
\newcommand{\SCons}{\texttt{SCons}}
\newcommand{\RCons}{\texttt{RCons}}
\newcommand{\rcons}{\texttt{rcons}}

\newcommand{\buildfile}{\textit{build file}}


%
% Package Setup
%

% float package
\restylefloat{figure}

% fancyhdr package
\pagestyle{fancy}

\fancyhf{}
\newlength{\hfoffset}\setlength{\hfoffset}{8pt}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
\fancyhfoffset{\hfoffset}
\lhead{\hspace{\hfoffset}\textsf{\footnotesize \mytitle: \mysubtitle}}
\lfoot{\hspace{\hfoffset}\textsf{\footnotesize \myclassnum, \mysemester}}
\fancyhf[R]{\textsf{\footnotesize \thepage\ of \pageref*{LastPage}}\hspace{\hfoffset}}

\fancypagestyle{title}{%
	\fancyhf{}
	\renewcommand{\headrulewidth}{0pt}
	\renewcommand{\footrulewidth}{0.4pt}
	\lfoot{\hspace{\hfoffset}\textsf{\footnotesize \myclassnum, \mysemester}}
	\rfoot{\textsf{\footnotesize \thepage\ of \pageref*{LastPage}}\hspace{\hfoffset}}}

\renewcommand{\theenumi}{\arabic{enumi}}
\renewcommand{\theenumii}{.\arabic{enumii}}
\renewcommand{\theenumiii}{.\arabic{enumiii}}
\renewcommand{\theenumiv}{.\arabic{enumiv}}

\renewcommand{\labelenumi}{\footnotesize\theenumi}
\renewcommand{\labelenumii}{\footnotesize\theenumi\theenumii}
\renewcommand{\labelenumiii}{\footnotesize\theenumi\theenumii\theenumiii}
\renewcommand{\labelenumiv}{\footnotesize\theenumi\theenumii\theenumiii\theenumiv}

\newenvironment{code}%
{\begin{centering}
	\begin{tabular*}{0.8\textwidth}{@{\vline\hspace{4pt}}l@{\extracolsep{\fill}}}}%
	{\end{tabular*}
\end{centering}}


\begin{document}
\thispagestyle{title}
\begin{adjustwidth}{-8pt}{-8pt}
	\begin{tabular*}{\textwidth+16pt}{@{\hspace{8pt}}l@{\extracolsep{\fill}}r@{\hspace{8pt}}}
		\textbf{\LARGE \mytitle} & \\
		\textbf{\large \mysubtitle}\smallskip & \\
	\end{tabular*}
	\begin{tabular*}{\textwidth+16pt}{@{\hspace{8pt}}l@{\extracolsep{\fill}}r@{\hspace{8pt}}}
		\textsf{\small \myauthors} & \textsf{\small \myclassname} \\
		\hline
	\end{tabular*}
\end{adjustwidth}
\lstset{language=Ruby,tabsize=2}

\section{Overview}

RCons is a software development tool designed to be used instead of 'make' when 
compiling software projects. It will take a file or list of files to be 
compiled, and create the dependency tree for the project. It will then compile 
and build the project.

The goal of \RCons\ software is to be an easy-to-learn, easy-to-use alternative 
to 'make' files, which can be long and confusing. It will be a smart system, 
detecting code-specific changes in the dependent files.

RCons is created as an open-source project for the use of developers everywhere 
to modify and extend the current functionality. \RCons\ is a good alternative to 
'make' because of the readability and comprehensibility of the code. Even those 
without Ruby experience can learn the easy-to-use commands quickly and then be 
able to start utilizing this tool. Ruby also allows the use of any Ruby 
constructs. Ruby contains tools to debug, even after modification. The language 
is clean and efficient and syntax evaluation is simple. There is also no need 
to do a 'make clean' and 'make all' each time you want to compile your project.

RCons is not the only make replacement tool, and other similar projects are 
included here as links for potential users and developers.

\begin{itemize}
	\item \url{http://directory.fsf.org/bras.html} -- Bras, one of earliest 	
		implementations of "make in a scripting language".
	\item \url{http://www.a-a-p.org/} -- Make in Python
	\item \url{http://www.aromatic.com/tools/jam.txt} -- JAM, Java Automated Make
	\item \url{http://ppt.perl.org/commands/make/index.html} -- Make from the 
		Perl Power Tools implementation.
	\item \url{http://make.rubyforge.org/} -- Rant, another Ruby make tool.
\end{itemize}

\section{Introduction}

To use \RCons, the user must first download and install the special Ruby 
environment. \RCons\ has many features that are not necessary for every 
programmer. \RCons\ has the capability to compile single (though this is trivial) 
or multiple source files into a single or multiple applications.  These are the 
basic parameters for \RCons.

\subsection{Installation}

For installation of the required environment and program, please see the Ruby 
GEM docs included on the SourceForge project design page for rCons.

Use this link to view the RubyGems User Guide: \url{http://rubygems.org/read/book/1}

\subsection{10 Minute Quick Start}

This section will detail how Ruby can compile and build a basic program like 
"Hello World." 

To begin, the user should create two source files. For this example, one should 
be 'hello.c' and the other should be 'world.c' with the functionality of each 
to be merely printing their title (sans extension) to the terminal.


An example of this BuildFile appears as follows:
\begin{quote}
\begin{lstlisting}
helloWorld = CApplicationTarget.new( @build_env, 'helloWorld' ) do |app|
	app.add_sources( 'hello.c' )
	app.add_sources( 'world.c' )
end

add( helloWorld )
\end{lstlisting}
\end{quote}
The user will then open the Ruby environment and call \RCons\ to build the 
project. \RCons\ will then compile the source files, reporting errors if there 
are any, and then build the executable project 'helloWorld'.
\begin{quote}
\begin{lstlisting}[language=sh]
$ rcons
\end{lstlisting}
\end{quote}
The user will then run the application from the command line.
\begin{quote}
\begin{lstlisting}[language=sh]
$ ./helloWorld
\end{lstlisting}
\end{quote}
When the project is complete, the user may edit "hello.c" changing the output 
to all caps.
\begin{quote}
\begin{lstlisting}[language=sh]
$ vi hello.c
\end{lstlisting}
\end{quote}
After editing the file, the user will call \RCons\ again to re-build the 
project.
RCons will detect the change in "hello.c" and re-build the project.
\begin{quote}
\begin{lstlisting}[language=sh]
$ rcons
\end{lstlisting}
\end{quote}
RCons will then recompile "hello.c" but not "world.c" then build the project.
The user will then run the application from the command line again.
\begin{quote}
\begin{lstlisting}[language=sh]
$ ./helloWorld
\end{lstlisting}
\end{quote}
The user will notice the output has changed to reflect the changes to the code.

The \buildfile\ has the two source parameters "hello.c" and "world.c" in that 
order. Another source file may be added using the same syntax as displayed in 
the above \buildfile\ example. Suppose the user wants to output an additional 
phrase "I am alive" to the end of their existing helloWorld project.

The user will create a new c-source file called "lives.c" and add the code to 
print.
\begin{quote}
\begin{lstlisting}[language=sh]
$ vi lives.c
\end{lstlisting}
\end{quote}
The user will then have to open the example \buildfile\ as above, and add the 
line as such:
\begin{quote}
\begin{lstlisting}
helloWorld = CApplicationTarget.new( @build_env, 'helloWorld' ) do |app|
	app.add_sources( 'hello.c' )
	app.add_sources( 'world.c' )
	app.add_sources( 'lives.c' ) #ADD THIS LINE
end

add( helloWorld )
\end{lstlisting}
\end{quote}
The user will then call \RCons\ from the command line to re-build the project.
\begin{quote}
\begin{lstlisting}[language=sh]
$ rcons
\end{lstlisting}
\end{quote}
Finally the user may run the new project again, and it will output: "HELLO 
world I am here"
\begin{quote}
\begin{lstlisting}[language=sh]
$ ./helloWorld
\end{lstlisting}
\end{quote}

\section{Command Line Usage}

Some of the options included with rCons are detailed here. Using the '--help' 
option will fully detail the list of potential options and their usage.

\begin{description}
	\item[\texttt{--build} (\texttt{-b})]	Default action used to build the listed 
		targets. This is the primary action that \RCons\ will perform.
	\item[\texttt{--list-targets} (-l)]	List available targets for this build.  
		This goes through the \buildfile\ and finds all targets defined or 
		generated from there.
	\item[\texttt{--help} (-h)]	Shows help text, including most of this 
		information.
	\item[\texttt{--version}]	Shows the version information.
	\item[\texttt{--[no-]verbose} (-v)] Runs \RCons\ verbosely, allowing output 
		of more detailed information when that is desirable or necessary
\end{description}

\section{Writing a \buildfile}

The \buildfile\ is executed in Ruby with a special context provided by
RCons.  This context allows all Ruby functionality, and in addition,
provides classes and methods which allow the different parts of an
application to be specified and built.  Therefore, in addition to
using the classes and methods provided by \RCons, Ruby constructs can
be used to tailor the \buildfile\ to specific applications.

\subsection{Specifying environment information}

Environments contain information such as the current working path an
environment variables.  The following example defines an environment with
a simple environment variable.

\begin{quote}
\begin{lstlisting}
test_env = Environment.new( 'test', '.', 'build' )
\end{lstlisting}
\end{quote}

An \texttt{Environment} object called \texttt{test\_env} will be created. As
specified by the parameters, the environment's name will be 'test
environment', the source root directory will be the directory in which
the \buildfile\ is located, and the build directory will be the
directory 'build/debug' relative to the \buildfile.

\subsection{Defining an Application}

Information relevant to an Application is managed by an Application
target.  An example of creating an application target for the C
language is shown below:

\begin{quote}
\begin{lstlisting}
test_app = CApplicationTarget.new( test_env, 'test_app' )
\end{lstlisting}
\end{quote}

An \texttt{Application} object called \texttt{test\_app} will be created.  The
parameters specify an \texttt{Environment} given by \texttt{test\_env} and the 
name
of the application will be 'test application'.

\subsection{Adding Source Files to an Application}

Once an \texttt{Application} object has been created, source code files must
be associated with it.  The following code associates a few source
files with an \texttt{Application} object.

\begin{quote}
\begin{lstlisting}
test_app.add_sources( 'src1.c' )
test_app.add_sources( 'src2.c' )
test_app.add_sources( 'src3.c' )
\end{lstlisting}
\end{quote}

The files 'src1.c', 'src2.c' and 'src3.c' relative to the source root
defined by the environment associated with \texttt{test\_app} will be added to
the application.

\subsection{Setting Default Build Targets}

In addition to defining applications to be built in a \buildfile, the
default application(s) must also be defined.  Any application added to
the default list will be automatically build when the \buildfile\ is
executed with no build target specified.  Default applications are
specified by:

\begin{quote}
\begin{lstlisting}
add( test_app )
\end{lstlisting}
\end{quote}

\subsection{Example \buildfile}

Putting together each of the concepts previously explained, the
following \buildfile\ defines an environment, an application with a few
source files, and adds that application to the default build list.

\begin{quote}
\begin{lstlisting}
test_env = Environment.new( 'test', '.', 'build' )

test_app = CApplicationTarget.new( test_env, 'test_app' )

test_app.add_sources( 'src1.c' )
test_app.add_sources( 'src2.c' )
test_app.add_sources( 'src3.c' )

add( test_app )
\end{lstlisting}
\end{quote}

\clearpage
\subsection{A Practical Example}

The previous example used constructs provided by \RCons\ to specify a
build process.  Since \RCons\ uses the Ruby context for execution, Ruby
constructs can also be used within the \buildfile.  Following is a more
practical example of a \buildfile.

\begin{figure}[H]
\begin{lstlisting}
# Create debug and release environments
debug_env = Environment.new( 'debug', '.', 'build/debug' )
release_env = Environment.new( 'release', '.', 'build/release' )

# Specify sources for the parser.
parser_sources = [ 'src/Token/Token.cpp', 'src/HashTable/SymbolTable.cpp',
									'src/Lexer/Lexer.cpp', 'src/parser.cpp' ]

# Specify sources for the compiler.
compiler_sources = [ 'src/compiler.cpp' ]

# Create an application for debugging the parser.
parser_debug = CxxApplicationTarget.new( debug_env, 'parser' ) do |a|
	a.add_sources( *parser_sources )
end

# Create a release application for the parser.
parser_release = CxxApplicationTarget.new( release_env, 'parser' ) do |a|
	a.add_sources( *parser_sources )
end

# Create a debug application for the compiler.
compiler_debug = CxxApplicationTarget.new( debug_env, 'compiler' ) do |a|
	a.add_sources( *parser_sources, *compiler_sources )
end

# Create a release application for the compiler.
compiler_release = CxxApplicationTarget.new( release_env, 'compiler' ) do |a|
	a.add_sources( *parser_sources, *compiler_sources )
end

# Specify build targets.
add( parser_release, compiler_release )
\end{lstlisting}
\end{figure}

\section{Extension of \RCons}

Extending this tool to support new and custom features is very easily done. The 
ruby-nature of build files allows a great deal of freedom, and more can be 
achieved readily. The online documentation available at 
\url{http://rcons.sourceforge.net/rdoc/} provide a cross referenced set of 
extensive documentation of the source code, and how to use and extend \RCons.

\section{License}

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

\section{Support}

The \RCons\ page is hosted on SourceForge.  

Feel free to submit bugs or feature requests.  If you send a patch,
remember to update the corresponding unit tests.  It is preferred
that all new features are submitted in the form of new unit tests.

\section{Warranty}

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

\end{document}

